<HTML><HEAD><TITLE>cursor_next_execute(++Cursor, +Tuple, ++Options)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">library(dbi)</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>cursor_next_execute(++Cursor, +Tuple, ++Options)</H1>
Executes the parametrised prepared SQL statement represented by Cursor, with options Options.
<DL>
<DT><EM>Cursor</EM></DT>
<DD>A cursor handle
</DD>
<DT><EM>Tuple</EM></DT>
<DD>A tuple of parameter values matching the template for this cursor (structure)
</DD>
<DT><EM>Options</EM></DT>
<DD>Options (list of Option:Value pairs or nil)
</DD>
</DL>
<H2>Description</H2>
<P>
 Executes the parameterised prepared SQL statement represented by Cursor,
 previously prepared by session_sql_prepare/4 or session_sql_prepare_query/5.
 The parameter values for this execution is supplied by Tuple. Options is 
 a (possibly empty) list of <TT>Option:Value</TT> pairs, specifying 
 DBMS-specific options for the cursor.
</P><P>
 Tuple is a structure whose name and arity match the parameter template
 when Cursor was prepared, and the arguments give the values for the
 parameters for this execution, and must be compatible with the type
 specified by the template, except that an argument can be an
 uninstantiated variable, to denote a NULL value for the corresponding
 parameter.
</P><P>
 If the SQL statement is a query, and was prepared as a query using
 session_sql_prepare_query/5, results can be obtained from the query by
 the cursor_*_tuple family of predicates.
</P><P>
 MySQL specific:
</P><P>
 Options is used to specify the type of cursor used. Currently this only
 applies to cursors for SQL queries. The options are:
<DL>
<P>
<DT><STRONG><TT>buffering</TT></STRONG>
<DD>Specifies where the result set of a SQL query is buffered. Value can be
 either <TT>client</TT> (the default) or <TT>server</TT>. By default, the
 whole of the result set for a query is copied to the client (i.e. the
 ECLiPSe process running lib(dbi)) after the SQL query is executed. The 
 alternative is to leave the result set on the DBMS server, and only get
 the result tuples from the server one by one (with e.g. cursor_next_tuple/2).
 </P><P>
 The default buffering is on the client side, because this is the default
 of the MySQL C API, and in addition, it imposes certain restrictions on
 how the result tuples can be retrieved. However, as the whole result set
 is retreived, this can impose significant memory overheads if there are
 many tuples in the result set.
 </P><P>
<DT><STRONG><TT>type</TT></STRONG>
<DD>Specifies the type of cursor, and is only meaningful if the buffering
 option is set to server. Value can be either <TT>no_cursor</TT> (the
 default) or <TT>read_only</TT>.  These correspond to the MySQL statement 
 attribute STMT_ATTR_CURSOR_TYPE of CURSOR_TYPE_NO_CURSOR and 
 CURSOR_TYPE_READ_ONLY respectively (See the MySQL manual for details).
</P><P>
 Only one active cursor of type no_cursor is allowed per session, and this
 active cursor must be closed before another query can be issued to the
 DBMS server. read_only cursor does not have this restriction, and several
 such cursors can be active at the same time. 
</DL>

<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>Cursor is not a valid cursor handle
<DT><EM>(5) type error </EM>
<DD>Type mismatch between parameter template specification for Cursor and actual tuple data
<DT><EM>(6) out of range </EM>
<DD>Invalid option specification in Options
<DT><EM>(dbi_buffer_over) </EM>
<DD>Parameter value(s) too big for the buffer
<DT><EM>(dbi_error) </EM>
<DD>Error from DBMS while executing SQL associated with Cursor.
<DT><EM>(dbi_bad_template) </EM>
<DD>ParamTemplate not specified when Cursor was created
<DT><EM>(dbi_bad_cursor) </EM>
<DD>The Cursor is not in a state to execute a query (e.g. it was cancelled)
</DL>
<H2>See Also</H2>
<A HREF="../../lib/dbi/cursor_next_execute-2.html">cursor_next_execute / 2</A>, <A HREF="../../lib/dbi/cursor_all_execute-2.html">cursor_all_execute / 2</A>, <A HREF="../../lib/dbi/cursor_N_execute-4.html">cursor_N_execute / 4</A>, <A HREF="../../lib/dbi/session_sql_prepare-4.html">session_sql_prepare / 4</A>, <A HREF="../../lib/dbi/session_sql_prepare_query-5.html">session_sql_prepare_query / 5</A>
</BODY></HTML>
